<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=iso-8859-1">
<title>Registering a Custom Renderer with a Render Kit - The Java EE 5 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2008-10-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/j5eetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnafd.html">4.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnagx.html">5.&nbsp;&nbsp;JavaServer Pages Technology</a></p>
<p class="toc level2"><a href="bnajo.html">6.&nbsp;&nbsp;JavaServer Pages Documents</a></p>
<p class="toc level2"><a href="bnakc.html">7.&nbsp;&nbsp;JavaServer Pages Standard Tag Library</a></p>
<p class="toc level2"><a href="bnalj.html">8.&nbsp;&nbsp;Custom Tags in JSP Pages</a></p>
<p class="toc level2"><a href="bnaon.html">9.&nbsp;&nbsp;Scripting in JSP Pages</a></p>
<p class="toc level2"><a href="bnaph.html">10.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnaqz.html">11.&nbsp;&nbsp;Using JavaServer Faces Technology in JSP Pages</a></p>
<p class="toc level2"><a href="bnatx.html">12.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnavg.html">13.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnawo.html">14.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level3"><a href="bnawp.html">Application Configuration Resource File</a></p>
<p class="toc level3"><a href="bnawq.html">Configuring Beans</a></p>
<p class="toc level4"><a href="bnawq.html#bnawr">Using the <tt>managed-bean</tt> Element</a></p>
<p class="toc level4"><a href="bnawq.html#bnaws">Initializing Properties Using the <tt>managed-property</tt> Element</a></p>
<p class="toc level5"><a href="bnawq.html#bnawu">Referencing a Java <tt>Enum</tt> Type</a></p>
<p class="toc level5"><a href="bnawq.html#bnawv">Referencing an Initialization Parameter</a></p>
<p class="toc level5"><a href="bnawq.html#bnaww">Initializing Map Properties</a></p>
<p class="toc level5"><a href="bnawq.html#bnawx">Initializing Array and List Properties</a></p>
<p class="toc level5"><a href="bnawq.html#bnawy">Initializing Managed Bean Properties</a></p>
<p class="toc level4 tocsp"><a href="bnawq.html#bnaxa">Initializing Maps and Lists</a></p>
<p class="toc level3 tocsp"><a href="bnaxb.html">Registering Custom Error Messages</a></p>
<p class="toc level3"><a href="bnaxc.html">Registering Custom Localized Static Text</a></p>
<p class="toc level3"><a href="bnaxd.html">Registering a Custom Validator</a></p>
<p class="toc level3"><a href="bnaxe.html">Registering a Custom Converter</a></p>
<p class="toc level3"><a href="bnaxf.html">Configuring Navigation Rules</a></p>
<div class="onpage">
<p class="toc level3"><a href="">Registering a Custom Renderer with a Render Kit</a></p>
</div>
<p class="toc level3"><a href="bnaxi.html">Registering a Custom Component</a></p>
<p class="toc level3"><a href="bnaxj.html">Basic Requirements of a JavaServer Faces Application</a></p>
<p class="toc level4"><a href="bnaxj.html#bnaxk">Configuring an Application with a Deployment Descriptor</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxl">Identifying the Servlet for Life Cycle Processing</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxm">Specifying a Path to an Application Configuration Resource File</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxn">Specifying Where State Is Saved</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxo">Encrypting Client State</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxp">Restricting Access to JavaServer Faces Components</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxq">Turning On Validation of XML Files</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxr">Verifying Custom Objects</a></p>
<p class="toc level4 tocsp"><a href="bnaxj.html#bnaxs">Including the Required JAR Files</a></p>
<p class="toc level4"><a href="bnaxj.html#bnaxt">Including the Classes, Pages, and Other Resources</a></p>
<p class="toc level2 tocsp"><a href="bnaxu.html">15.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">16.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="bnazf.html">17.&nbsp;&nbsp;Binding between XML Schema and Java Classes</a></p>
<p class="toc level2"><a href="bnbdv.html">18.&nbsp;&nbsp;Streaming API for XML</a></p>
<p class="toc level2"><a href="bnbhf.html">19.&nbsp;&nbsp;SOAP with Attachments API for Java</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbls.html">20.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbnb.html">21.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="bnboc.html">22.&nbsp;&nbsp;Session Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">23.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;V&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">24.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="bnbrl.html">25.&nbsp;&nbsp;Persistence in the Web Tier</a></p>
<p class="toc level2"><a href="bnbrs.html">26.&nbsp;&nbsp;Persistence in the EJB Tier</a></p>
<p class="toc level2"><a href="bnbtg.html">27.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level1 tocsp"><a href="bnbwi.html">Part&nbsp;VI&nbsp;Services</a></p>
<p class="toc level2"><a href="bnbwj.html">28.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bnbyk.html">29.&nbsp;&nbsp;Securing Java EE Applications</a></p>
<p class="toc level2"><a href="bncas.html">30.&nbsp;&nbsp;Securing Web Applications</a></p>
<p class="toc level2"><a href="bncdq.html">31.&nbsp;&nbsp;The Java Message Service API</a></p>
<p class="toc level2"><a href="bncgv.html">32.&nbsp;&nbsp;Java EE Examples Using the JMS API</a></p>
<p class="toc level2"><a href="bncih.html">33.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">34.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncjx.html">35.&nbsp;&nbsp;Connector Architecture</a></p>
<p class="toc level1 tocsp"><a href="bnckn.html">Part&nbsp;VII&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="bncko.html">36.&nbsp;&nbsp;The Coffee Break Application</a></p>
<p class="toc level2"><a href="bnclz.html">37.&nbsp;&nbsp;The Duke's Bank Application</a></p>
<p class="toc level1 tocsp"><a href="gexbq.html">Part&nbsp;VIII&nbsp;Appendixes</a></p>
<p class="toc level2"><a href="bncno.html">A.&nbsp;&nbsp;Java Encoding Schemes</a></p>
<p class="toc level2"><a href="bncnq.html">B.&nbsp;&nbsp;Preparation for Java EE Certification Exams</a></p>
<p class="toc level2"><a href="bncnt.html">C.&nbsp;&nbsp;About the Authors</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td width="705px">
         <div class="header">
             <div class="header-links-top">
                 <a href="http://java.sun.com">java.sun.com</a> |
                 <a href="http://docs.sun.com/">docs.sun.com</a><br>
             </div> 
             <img src="graphics/tutorialBanner.gif" width="704" height="120" alt="The Java&trade; EE 5 Tutorial"/>
             <div class="header-links">
	         <a href="index.html">Home</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/download.html">Download</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/JavaEETutorial.pdf">PDF</a> |
                 <a href="http://java.sun.com/javaee/5/docs/api/index.html">API</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/faq.html">FAQ</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/search.html">Search</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html">Feedback</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/history.html">History</a>
             </div>
             <div class="navigation">
                 <a href="bnaxf.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
                 <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
                 <a href="bnaxi.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnaxh"></a><h3>Registering a Custom Renderer with a Render Kit</h3>
<a name="indexterm-1616"></a><a name="indexterm-1617"></a><a name="indexterm-1618"></a><p><a name="indexterm-1619"></a><a name="indexterm-1620"></a><a name="indexterm-1621"></a>When the application developer creates a custom renderer, as described in <a href="bnawa.html">Delegating Rendering to a Renderer</a>, you
must register it using the appropriate render kit. Because the image map application
implements an HTML image map, <tt>AreaRenderer</tt> (as well as <tt>MapRenderer</tt>) should be
registered using the HTML render kit.</p><p><a name="indexterm-1622"></a>You register the renderer using the <tt>render-kit</tt> element of the application configuration resource file.
Here is the configuration of <tt>AreaRenderer</tt> from the Duke&rsquo;s Bookstore application:</p><pre>&lt;render-kit>
    &lt;renderer>
        &lt;component-family>Area&lt;/component-family>
        &lt;renderer-type>DemoArea&lt;/renderer-type>
        &lt;renderer-class>
            com.sun.bookstore6.renderers.AreaRenderer
        &lt;/renderer-class>
        &lt;attribute>
            &lt;attribute-name>onmouseout&lt;/attribute-name>
            &lt;attribute-class>java.lang.String&lt;/attribute-class>
        &lt;/attribute>
        &lt;attribute>
            &lt;attribute-name>onmouseover&lt;/attribute-name>
            &lt;attribute-class>java.lang.String&lt;/attribute-class>
        &lt;/attribute>
        &lt;attribute>
            &lt;attribute-name>styleClass&lt;/attribute-name>
            &lt;attribute-class>java.lang.String&lt;/attribute-class>
        &lt;/attribute>
    &lt;/renderer>
    ...</pre><p><a name="indexterm-1623"></a><a name="indexterm-1624"></a><a name="indexterm-1625"></a><a name="indexterm-1626"></a>The <tt>render-kit</tt> element represents a <tt>RenderKit</tt> implementation. If no <tt>render-kit-id</tt> is specified, the default
HTML render kit is assumed. The <tt>renderer</tt> element represents a <tt>Renderer</tt> implementation. By
nesting the <tt>renderer</tt> element inside the <tt>render-kit</tt> element, you are registering the renderer
with the <tt>RenderKit</tt> implementation associated with the <tt>render-kit</tt> element.</p><p>The <tt>renderer-class</tt> is the fully qualified class name of the <tt>Renderer</tt>.</p><p>The <tt>component-family</tt> and <tt>renderer-type</tt> elements are used by a component to find renderers
that can render it. The <tt>component-family</tt> identifier must match that returned by
the component class&rsquo;s <tt>getFamily</tt> method. The component family represents a component or set
of components that a particular renderer can render. The <tt>renderer-type</tt> must match
that returned by the <tt>getRendererType</tt> method of the tag handler class.</p><p>By using the component family and renderer type to look up renderers for
components, the JavaServer Faces implementation allows a component to be rendered by multiple
renderers and allows a renderer to render multiple components.</p><p>Each of the <tt>attribute</tt> tags specifies a render-dependent attribute and its type. The
<tt>attribute</tt> element doesn&rsquo;t affect the runtime execution of your application. Instead, it provides
information to tools about the attributes the <tt>Renderer</tt> supports.</p><p>The object that is responsible for rendering a component (be it the component
itself or a renderer to which the component delegates the rendering) can use
facets to aid in the rendering process. These facets allow the custom component
developer to control some aspects of rendering the component. Consider this custom component
tag example:</p><pre>&lt;d:dataScroller>
    &lt;f:facet name="header">
        &lt;h:panelGroup>
            &lt;h:outputText value="Account Id"/>
            &lt;h:outputText value="Customer Name"/>
            &lt;h:outputText value="Total Sales"/>
        &lt;/h:panelGroup>
    &lt;/f:facet>
    &lt;f:facet name="next">
        &lt;h:panelGroup>
            &lt;h:outputText value="Next"/>
            &lt;h:graphicImage url="/images/arrow-right.gif" />
        &lt;/h:panelGroup>
    &lt;/f:facet>
        ...
&lt;/d:dataScroller></pre><p>The <tt>dataScroller</tt> component tag includes a component that will render the header and
a component that will render the Next button. If the renderer associated with
this component renders the facets you can include the following <tt>facet</tt> elements in
the <tt>renderer</tt> element:</p><pre>&lt;facet>
    &lt;description>This facet renders as the
         header of the table. It should be a panelGroup
         with the same number of columns as the data
    &lt;/description>
    &lt;display-name>header&lt;/display-name>
    &lt;facet-name>header&lt;/facet-name>
&lt;/facet>
 &lt;facet>
    &lt;description>This facet renders as the content
         of the "next" button in the scroller. It should be a
         panelGroup that includes an outputText tag that
         has the text "Next" and a right arrow icon.
    &lt;/description>
     &lt;display-name>Next&lt;/display-name>
    &lt;facet-name>next&lt;/facet-name>
&lt;/facet></pre><p>If a component that supports facets provides its own rendering and you want
to include <tt>facet</tt> elements in the application configuration resource file, you need to
put them in the component&rsquo;s configuration rather than the renderer&rsquo;s configuration.</p>
         </div>
         <div class="navigation">
             <a href="bnaxf.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
             <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
             <a href="bnaxi.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
         </div>

         <div class="copyright">
      	    <p>The material in The Java&trade; EE 5 Tutorial is <a href='docinfo.html'>copyright</a>-protected and may not be published in other works without express written permission from Sun Microsystems.</p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

